home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / Vk / VkCutPaste.z / VkCutPaste
Encoding:
Text File  |  2001-04-17  |  62.5 KB  |  1,519 lines
  1.  
  2.  
  3.  
  4. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      VkCutPaste - A simple API for Cut/Copy/Drag/Drop
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      VkCallbackObject : VkBase
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <Vk/VkCutPaste.h>
  16.  
  17. PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
  18.    CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
  19.            VkCutPaste(Widget w);
  20.            void ~VkCutPaste(void);
  21.  
  22.  
  23.    CCCCooooppppyyyy ((((EEEExxxxppppoooorrrrtttt)))) MMMMeeeetttthhhhooooddddssss
  24.            void clear(Atom selection, Time time = CurrentTime);
  25.            Boolean putCopy(Atom selection, Atom target,
  26.                            XtPointer data, unsigned long numBytes);
  27.            Boolean putCopy(Atom selection, const char *targetName,
  28.                            XtPointer data, unsigned long numBytes);
  29.            Boolean putReference(Atom selection, Atom target,
  30.                            XtPointer data, unsigned long numBytes);
  31.            Boolean putReference(Atom selection,
  32.                            const char *targetName,
  33.                            XtPointer data, unsigned long numBytes);
  34.            Boolean getLocalReference(Atom selection, int index,
  35.                            Atom *target, XtPointer *dataRet,
  36.                            unsigned long *numBytesRet);
  37.            Boolean getLocalTypeReference(Atom selection,
  38.                            Atom target, XtPointer *dataRet,
  39.                            unsigned long *numBytesRet);
  40.            Boolean remove(Atom selection, Atom target);
  41.  
  42.  
  43.    CCCCooooppppyyyy ((((EEEExxxxppppoooorrrrtttt)))) MMMMeeeetttthhhhooooddddssss ---- VVVViiiieeeewwwwKKKKiiiitttt 1111....5555....3333 oooonnnnllllyyyy
  44.            Boolean export(Atom selection, Time time = CurrentTime);
  45.  
  46.  
  47.    CCCCooooppppyyyy ((((EEEExxxxppppoooorrrrtttt)))) MMMMeeeetttthhhhooooddddssss ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy
  48.            Boolean exportData(Atom selection, Time time = CurrentTime);
  49.  
  50.  
  51.  
  52.    PPPPaaaasssstttteeee ((((IIIImmmmppppoooorrrrtttt)))) MMMMeeeetttthhhhooooddddssss
  53.            void import(Atom selection, Atom *interestList,
  54.                        int interestListLen, ImportCallbackProc proc,
  55.                        void *clientData = NULL,
  56.                        Time theTime = CurrentTime);
  57.            XtPointer importImmediate(Atom selection,
  58.                        Atom *interestList, int interestListLen,
  59.                        Atom *targetRet, unsigned long *numBytesRet,
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  71.  
  72.  
  73.  
  74.                        Time theTime = CurrentTime);
  75.  
  76.  
  77.    DDDDrrrraaaagggg AAAAwwwwaaaayyyy MMMMeeeetttthhhhooooddddssss
  78.            Widget dragAwayCopy(Widget w, XEvent *xev, Atom target,
  79.                        XtPointer data, unsigned long numBytes,
  80.                        DragAwayCallbackProc dragAwayProc = NULL,
  81.                        void *clientData = NULL);
  82.            Widget dragAwayCopy(Widget w, XEvent *xev,
  83.                        const char *targetName,
  84.                        XtPointer data, unsigned long numBytes,
  85.                        DragAwayCallbackProc dragAwayProc = NULL,
  86.                        void *clientData = NULL);
  87.            Widget dragAwayCopyExtended(Widget w, XEvent *xev,
  88.                        Atom *targetList, XtPointer *dataList,
  89.                        unsigned long *lenList, int numDragItems,
  90.                        DragAwayCallbackProc dragAwayProc = NULL,
  91.                        void *clientData = NULL,
  92.                        ArgList args = NULL, int numArgs = 0);
  93.  
  94.  
  95.    DDDDrrrroooopppp MMMMeeeetttthhhhooooddddssss
  96.            Boolean registerDropSite(Widget w,
  97.                        Atom *interestList, int interestListLen,
  98.                        DropSiteCallbackProc dropProc,
  99.                        void *clientData = NULL);
  100.            Boolean registerDropSiteExtended(Widget w,
  101.                        Atom *interestList, int interestListLen,
  102.                        DropSiteCallbackProc dropProc,
  103.                        DragCallbackProc dragProc = NULL,
  104.                        void *clientData = NULL,
  105.                        Arg *args = NULL, int numArgs = 0);
  106.            Boolean unregisterDropSite(Widget w);
  107.  
  108.  
  109.    DDDDaaaattttaaaa TTTTyyyyppppeeee aaaannnndddd CCCCoooonnnnvvvveeeerrrrtttteeeerrrr MMMMeeeetttthhhhooooddddssss
  110.            void registerDataType(Atom target, Atom type, int format,
  111.                        unsigned long flags = CUTPASTE_NORMAL_TYPE,
  112.                        DestroyProc destroyProc = NULL,
  113.                        void *clientData = NULL);
  114.            void registerDataType(const char *targetName,
  115.                        const char *typeName, int format,
  116.                        unsigned long flags = CUTPASTE_NORMAL_TYPE,
  117.                        DestroyProc destroyProc = NULL,
  118.                        void *clientData = NULL);
  119.            Boolean getDataTypeInfo(Atom target, Atom *type,
  120.                        int *format, unsigned long *flags);
  121.            void registerConverter(Atom from, Atom to,
  122.                        ConvertProc converter,
  123.                        CanConvertProc canConvert = NULL,
  124.                        void *clientData = NULL);
  125.            void registerConverter(const char *fromName,
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  137.  
  138.  
  139.  
  140.                        const char *toName, ConvertProc converter,
  141.                        CanConvertProc canConvert = NULL,
  142.                        void *clientData = NULL);
  143.  
  144.  
  145.    OOOOtttthhhheeeerrrr MMMMeeeetttthhhhooooddddssss
  146.            unsigned long getVersion(void);
  147.            Atom primaryAtom(void);
  148.            Atom clipboardAtom(void);
  149.            Widget getWidget(void);
  150.            Time getXServerTime(void);
  151.            void setTransactionsTimeout(unsigned long numSeconds);
  152.            Boolean isOwnedByMe(Atom selection);
  153.            Boolean isOwnedByLocalHost(Atom selection);
  154.            Boolean registerLoseSelection(Atom selection,
  155.                        LoseSelectionProc loseSelProc,
  156.                        void *clientData);
  157.            Boolean getFilenamesFromSGI_ICON(char *sgiIconData,
  158.                        unsigned long numBytes,
  159.                        char ***fileNameArrayRet, int *numFilesRet);
  160.            void freeFilenamesFromSGI_ICON(char **fileNameArray,
  161.                        int numFiles);
  162.  
  163.  
  164.    CCCCaaaallllllllbbbbaaaacccckkkk FFFFuuuunnnnccccttttiiiioooonnnn PPPPrrrroooottttoooottttyyyyppppeeeessss
  165.            typedef Boolean (*ConvertProc)(Widget w, Atom selection,
  166.              void *clientData, Atom srcTarget, XtPointer src,
  167.              unsigned long numSrcBytes, Atom dstTarget,
  168.              XtPointer *dst, unsigned long *numDstBytes);
  169.            typedef Boolean (*CanConvertProc)(Widget w,
  170.              Atom selection, void *clientData, Atom srcTarget,
  171.              XtPointer src, unsigned long numSrcBytes,
  172.              Atom dstTarget);
  173.            typedef void (*DestroyProc)(Widget w, Atom selection,
  174.              Atom target, XtPointer data, unsigned long numBytes,
  175.              void *clientData);
  176.            typedef void (*LoseSelectionProc)(Widget w,
  177.              Atom selection, void *clientData);
  178.            typedef void (*DropSiteCallbackProc)(Widget w,
  179.              Atom target, XtPointer data, unsigned long numBytes,
  180.              int x, int y, void *clientData);
  181.            typedef void (*DragCallbackProc)(Widget w, Atom target,
  182.              int reason, int x, int y, void *clientData);
  183.            typedef void (*DragAwayCallbackProc)(Widget w,
  184.              Boolean result,void *clientData);
  185.            typedef void (*ImportCallbackProc)(Widget w, Atom target,
  186.              XtPointer data, unsigned long numBytes,
  187.              void *clientData);
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  203.  
  204.  
  205.  
  206. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  207.           The VkCutPaste class provides a simple C++ API that helps developers
  208.           add inter-application Copy/Paste/Drag/Drop to their applications
  209.           with very little effort, and with little or no understanding of
  210.           Motif's and X-Window's complex protocols.
  211.  
  212.           The VkCutPaste library uses the Xt Intrinsics and Motif to implement
  213.           a totally standard X-Selection ICCCM compliant communication, so
  214.           your application must link with those libraries to use this API.
  215.           The VkCutPaste does not require other parts of ViewKit, and can be
  216.           used in a standard Motif application.
  217.  
  218. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  219.    VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee(((())))
  220.            VkCutPaste(Widget w);
  221.  
  222.  
  223.           Instantiates a VkCutPaste object.  The "w" must not be destroyed for
  224.           the life of this class, since it is used by the VkCutPaste class
  225.           during the execution of most of the methods.  Do not pass the same
  226.           widget into more than one concurrent instance of the VkCutPaste
  227.           class.
  228.  
  229.    ~~~~VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee(((())))
  230.            void ~VkCutPaste(void);
  231.  
  232.  
  233.           This deletes any remaining memory allocated by the VkCutPaste class.
  234.           Because the VkCutPaste class will sometimes create temporary files,
  235.           it is important to always call the destructor when you are through
  236.           with the class.
  237.  
  238.    cccclllleeeeaaaarrrr(((())))
  239.            void clear(Atom selection, Time time = CurrentTime);
  240.  
  241.  
  242.           Usually called immediately before a "putCopy()".  Clears the
  243.           indicated selection, and frees any memory that was allocated as part
  244.           of an earlier "putCopy()".  After a "clear()", no data is being
  245.           offered to any other ICCCM clients on this selection.  The
  246.           "selection" is either CLIPBOARD or PRIMARY.
  247.  
  248.    cccclllliiiippppbbbbooooaaaarrrrddddAAAAttttoooommmm(((())))
  249.            Atom clipboardAtom(void);
  250.  
  251.  
  252.           Returns the CLIPBOARD atom.  This is a convenience function, and
  253.           returns exactly the same thing as XmInternAtom(dpy, "CLIPBOARD",
  254.           False).
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  269.  
  270.  
  271.  
  272.    ddddrrrraaaaggggAAAAwwwwaaaayyyyCCCCooooppppyyyy(((())))
  273.            Widget dragAwayCopy(Widget w, XEvent *xev, Atom target,
  274.                        XtPointer data, unsigned long numBytes,
  275.                        DragAwayCallbackProc dragAwayProc = NULL,
  276.                        void *clientData = NULL);
  277.            Widget dragAwayCopy(Widget w, XEvent *xev,
  278.                        const char *targetName,
  279.                        XtPointer data, unsigned long numBytes,
  280.                        DragAwayCallbackProc dragAwayProc = NULL,
  281.                        void *clientData = NULL);
  282.  
  283.  
  284.           Drags away data from this application.  The "data" can be free'd
  285.           immediately after calling this function, because this function makes
  286.           a copy of the data for its use.  The "xev" should be the ButtonPress
  287.           event that the user did to initiate the drag.  The optional
  288.           "dragAwayProc" is called after the drag completes, and one of the
  289.           parameters to that function indicates if the drag was successful or
  290.           not.  The DragContext created for this drag and drop transaction is
  291.           returned (see XmDragStart).
  292.  
  293.    ddddrrrraaaaggggAAAAwwwwaaaayyyyCCCCooooppppyyyyEEEExxxxtttteeeennnnddddeeeedddd(((())))
  294.            Widget dragAwayCopyExtended(Widget w, XEvent *xev,
  295.                        Atom *targetList, XtPointer *dataList,
  296.                        unsigned long *lenList, int numDragItems,
  297.                        DragAwayCallbackProc dragAwayProc = NULL,
  298.                        void *clientData = NULL,
  299.                        ArgList args = NULL, int numArgs = 0);
  300.  
  301.  
  302.           This does exactly what "dragAwayCopy()" does, but provides more
  303.           options for the advanced programmer who needs more control.  For
  304.           example, the programmer could specify the drag away data as more
  305.           than one "target" (it should be the same conceptual object, just in
  306.           different formats, like GIF and XPM format data of the same image).
  307.           The programmer could also use this function to specify the various
  308.           drag icons by specifying those parameters in the "args" argument.
  309.           "Args" and "numArgs" are passed of to XmDragStart().  The following
  310.           "args" are not allowed:  XmNconvertProc, XmNdragOperations,
  311.           XmNexportTargets, XmNnumExportTargets, XmNclientData.  See the
  312.           XmDragContext man page for information on other valid arguments.
  313.           Motif's Drop Copy protocol (XmDROP_COPY) is the only drag and drop
  314.           operation supported.  The DragContext created for this drag and drop
  315.           transaction is returned (see XmDragStart).
  316.  
  317.    eeeexxxxppppoooorrrrtttt(((()))) ---- VVVViiiieeeewwwwKKKKiiiitttt 1111....5555....3333 oooonnnnllllyyyy
  318.            Boolean export(Atom selection,
  319.                           Time time = CurrentTime);
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  335.  
  336.  
  337.  
  338.           Usually called immediately after a "putCopy()", this makes the data
  339.           in the indicated selection available to other ICCCM clients.
  340.  
  341.    eeeexxxxppppoooorrrrttttDDDDaaaattttaaaa(((()))) ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy
  342.            Boolean exportData(Atom selection,
  343.                               Time time = CurrentTime);
  344.  
  345.  
  346.           Usually called immediately after a "putCopy()", this makes the data
  347.           in the indicated selection available to other ICCCM clients.
  348.  
  349.    ffffrrrreeeeeeeeFFFFiiiilllleeeennnnaaaammmmeeeessssFFFFrrrroooommmmSSSSGGGGIIII____IIIICCCCOOOONNNN(((())))
  350.            void freeFilenamesFromSGI_ICON(char **fileNameArray,
  351.                        int numFiles);
  352.  
  353.  
  354.           This frees the data that is returned from the
  355.           "getFilenamesFromSGI_ICON()" method.
  356.  
  357.    ggggeeeettttFFFFiiiilllleeeennnnaaaammmmeeeessssFFFFrrrroooommmmSSSSGGGGIIII____IIIICCCCOOOONNNN(((())))
  358.            Boolean getFilenamesFromSGI_ICON(char *sgiIconData,
  359.                        unsigned long numBytes,
  360.                        char ***fileNameArrayRet, int *numFilesRet);
  361.  
  362.  
  363.           This convenience method parses the data of target _SGI_ICON which
  364.           the SGI desktop uses to drag one or more files around.  An
  365.           application would call this function inside of its
  366.           "DropSiteCallbackProc" when it receives a target of _SGI_ICON.
  367.           After an application is done with the filename list, it should free
  368.           the memory allocated inside "getFilenamesFromSGI_ICON()" by calling
  369.           "freeFilenamesFromSGI_ICON()".
  370.  
  371.    ggggeeeettttDDDDaaaattttaaaaTTTTyyyyppppeeeeIIIInnnnffffoooo(((())))
  372.            Boolean getDataTypeInfo(Atom target, Atom *type,
  373.                        int *format, unsigned long *flags);
  374.  
  375.  
  376.           Given the "target", this method returns the "type" and the "format"
  377.           of this kind of target as specified by the ICCCM manual, and also
  378.           any associated "flags".  True is returned if the "target" was found,
  379.           and False otherwise.  The VkCutPaste class knows about an extensive
  380.           list of targets already.  This list can be added to by calling the
  381.           "registerDataType()" method.  The "flags" returned is a bit mask of
  382.           the following flags:  CUTPASTE_NORMAL_TYPE, CUTPASTE_FILENAME_TYPE,
  383.           and CUTPASTE_HIDDEN_TYPE.  See "registerDataType()" for more
  384.           information.
  385.  
  386.    ggggeeeettttLLLLooooccccaaaallllRRRReeeeffffeeeerrrreeeennnncccceeee(((())))
  387.            Boolean getLocalReference(Atom selection, int index,
  388.                      Atom *target, XtPointer *dataRet, unsigned long
  389.                      *numBytesRet);
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  401.  
  402.  
  403.  
  404.           Allows you to retrieve the contents of the local export selection.
  405.           This is NOT X Selections based.  This only gives you a pointer, so
  406.           the data must not be free'd or modified.  Returns a pointer to the
  407.           data at "index" (if multiple "putCopy()" were called, the first one
  408.           is at index 0, the second is at index 1, and so on).
  409.  
  410.    ggggeeeettttLLLLooooccccaaaallllTTTTyyyyppppeeeeRRRReeeeffffeeeerrrreeeennnncccceeee(((())))
  411.            Boolean getLocalTypeReference(Atom selection,
  412.                            Atom target, XtPointer *dataRet,
  413.                            unsigned long *numBytesRet);
  414.  
  415.  
  416.           Does exactly the same thing as "getLocalReference()", but instead of
  417.           specifying an "index", you specify the "target" you wish to retrieve
  418.           from the exported selection.
  419.  
  420.    ggggeeeettttVVVVeeeerrrrssssiiiioooonnnn(((())))
  421.            unsigned long getVersion(void);
  422.  
  423.  
  424.           Returns the version number of this implementation of the VkCutPaste
  425.           class.  For example, the first version is 0x010000, version 2.1 will
  426.           be 0x020100, etc.
  427.  
  428.    ggggeeeettttWWWWiiiiddddggggeeeetttt(((())))
  429.            Widget getWidget(void);
  430.  
  431.  
  432.           Returns the widget that was originally passed to the VkCutPaste
  433.           constructor.
  434.  
  435.    ggggeeeettttXXXXSSSSeeeerrrrvvvveeeerrrrTTTTiiiimmmmeeee(((())))
  436.            Time getXServerTime(void);
  437.  
  438.  
  439.           Invokes a round trip to the X-Server, and returns a server
  440.           timestamp.  Most applications should try to avoid this call and use
  441.           the "CurrentTime" flag to the VkCutPaste methods, or even better
  442.           should use the timestamp out of a recent X-Event.  However, there
  443.           are some rare situations where there are no X-Events handy and
  444.           CurrentTime will not work, so this convenience method is a failsafe
  445.           way to get a valid server timestamp.
  446.  
  447.    iiiimmmmppppoooorrrrtttt(((())))
  448.            void import(Atom selection, Atom *interestList,
  449.                        int interestListLen, ImportCallbackProc proc,
  450.                        void *clientData = NULL,
  451.                        Time theTime = CurrentTime);
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  467.  
  468.  
  469.  
  470.           This is a non-blocking method which will retrieve Copy and Paste
  471.           data from any ICCCM client.  The "selection" should be either
  472.           CLIPBOARD or PRIMARY.  The "interestList" is an ordered array of the
  473.           targets this application is interested in.  For example,
  474.           interestList[0] might be XPM, interestList[1] might be GIF_89, and
  475.           interestList[2] might be STRING.  In this example, you would set
  476.           "interestListLen" to be "3".  The "proc" will be invoked with either
  477.           NULL data, or an XPM, GIF_89, or STRING.  NULL simply means that
  478.           nothing was available of any of the requested types.  "import()"
  479.           makes a copy of the interestList, so you can free this data
  480.           immediately after this call completes (and before the "proc" is
  481.           called).
  482.  
  483.    iiiimmmmppppoooorrrrttttIIIImmmmmmmmeeeeddddiiiiaaaatttteeee(((())))
  484.            XtPointer importImmediate(Atom selection,
  485.                        Atom *interestList, int interestListLen,
  486.                        Atom *targetRet, unsigned long *numBytesRet,
  487.                        Time theTime = CurrentTime);
  488.  
  489.  
  490.           This is a blocking version of the "import()" method.  This function
  491.           blocks until the data is retrieved, so it eliminates the callback.
  492.           Since this function uses it's own internal event loop, clients that
  493.           are not using the standard "XtAppMainLoop()" (or in ViewKit are not
  494.           using the standard "app->run()") might want to avoid this call.
  495.  
  496.    iiiissssOOOOwwwwnnnneeeeddddBBBByyyyLLLLooooccccaaaallllHHHHoooosssstttt(((())))
  497.            Boolean isOwnedByLocalHost(Atom selection);
  498.  
  499.  
  500.           Returns True if the indicated selection is currently owned by a
  501.           client running on the same machine as this client.  This call is
  502.           useful if you are planning to copy and paste filenames with other
  503.           clients, since a file that is on a different machine is not
  504.           accessible to your client.  Some examples of filename targets are
  505.           XPM_FILE and GIF_89_FILE.  Data stream types like XPM and GIF_89 are
  506.           always safe and will always work, and should be used unless there is
  507.           some overwhelming reason to exchange filenames.
  508.  
  509.    iiiissssOOOOwwwwnnnneeeeddddBBBByyyyMMMMeeee(((())))
  510.            Boolean isOwnedByMe(Atom selection);
  511.  
  512.  
  513.           Returns True if the selection is currently owned by this client.
  514.           This can be used to optimize the "Paste()" function to be faster
  515.           when this client would have exchanged data with itself anyway.
  516.  
  517.    pppprrrriiiimmmmaaaarrrryyyyAAAAttttoooommmm(((())))
  518.            Atom primaryAtom(void);
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  533.  
  534.  
  535.  
  536.           Returns the PRIMARY atom.  This is a convenience function, and
  537.           returns exactly the same thing as XmInternAtom(dpy, "PRIMARY",
  538.           False).
  539.  
  540.    ppppuuuuttttCCCCooooppppyyyy(((())))
  541.            Boolean putCopy(Atom selection, Atom target,
  542.                            XtPointer data, unsigned long numBytes);
  543.            Boolean putCopy(Atom selection, const char *targetName,
  544.                            XtPointer data, unsigned long numBytes);
  545.  
  546.  
  547.           This method is usually called immediately after a "clear()" and
  548.           immediately before "export()" (or "exportData()" if using ViewKit
  549.           2.1). These three methods make the "data" specified in the putCopy()
  550.           available to any ICCCM client on the indicated "selection", which
  551.           should be either PRIMARY or CLIPBOARD.  The "data" passed into
  552.           "putCopy()" can be free'd immediately after this call, since
  553.           "putCopy()" makes a copy of the data.
  554.  
  555.    ppppuuuuttttRRRReeeeffffeeeerrrreeeennnncccceeee(((())))
  556.            Boolean putReference(Atom selection, Atom target,
  557.                            XtPointer data, unsigned long numBytes);
  558.            Boolean putReference(Atom selection,
  559.                            const char *targetName,
  560.                            XtPointer data, unsigned long numBytes);
  561.  
  562.  
  563.           This method can be used instead of "putCopy()" if the data is so
  564.           large that an extra copy is not possible or is terribly inefficient.
  565.           This call DOES NOT make a copy of the data, so you must not ever
  566.           free "data" until after you "remove()" this data from the currently
  567.           exported selection.  If for whatever reason the data becomes
  568.           invalid, you must call "remove()" to remove this reference.
  569.  
  570.    rrrreeeeggggiiiisssstttteeeerrrrCCCCoooonnnnvvvveeeerrrrtttteeeerrrr(((())))
  571.            void registerConverter(Atom from, Atom to,
  572.                        ConvertProc converter,
  573.                        CanConvertProc canConvert = NULL,
  574.                        void *clientData = NULL);
  575.            void registerConverter(const char *fromName,
  576.                        const char *toName, ConvertProc converter,
  577.                        CanConvertProc canConvert = NULL,
  578.                        void *clientData = NULL);
  579.  
  580.  
  581.           Registers a converter between two data targets.  The VkCutPaste
  582.           class provides integral support for converters.  Converters are used
  583.           to extend the targets that your application understands.  For
  584.           example, if you call "dragAway()" with XPM data (this is an image),
  585.           and a drop site in another ICCCM application only accepts images of
  586.           type GIF_89, then the drop would normally fail.  However, if you
  587.           have registered a converter from XPM to GIF_89, the VkCutPaste class
  588.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  599.  
  600.  
  601.  
  602.           will automatically call your converter and successfully drop the
  603.           GIF_89 on the destination client.  This same converter will fire if
  604.           you attempt to "import()" a GIF_89 yourself, yet the other client is
  605.           only offering XPM.  The converter is called to provide you with the
  606.           data type you requested.  The optional "canConvertProc" is provided
  607.           so that your application can conditionally offer conversion support
  608.           for a given target.  The "canConvert" function returns True if the
  609.           converter can perform the requested conversion, and False otherwise.
  610.           The "canConvert" function is called by VkCutPaste so that VkCutPaste
  611.           doesn't offer targets to requesting clients that cannot actually be
  612.           produced.  If your conversions will always work under all
  613.           circumstances, do not register a "CanConvertProc".
  614.  
  615.    rrrreeeeggggiiiisssstttteeeerrrrDDDDaaaattttaaaaTTTTyyyyppppeeee(((())))
  616.            void registerDataType(Atom target, Atom type, int format,
  617.                        unsigned long flags = CUTPASTE_NORMAL_TYPE,
  618.                        DestroyProc destroyProc = NULL,
  619.                        void *clientData = NULL);
  620.            void registerDataType(const char *targetName,
  621.                        const char *typeName, int format,
  622.                        unsigned long flags = CUTPASTE_NORMAL_TYPE,
  623.                        DestroyProc destroyProc = NULL,
  624.                        void *clientData = NULL);
  625.  
  626.  
  627.           Registers a data target with the VkCutPaste class, and at the same
  628.           time tells the class what the type, format, and flags are.  This is
  629.           only necessary if the VkCutPaste class has never heard of this
  630.           format before (the VkCutPaste class contains an extensive internal
  631.           list of known targets, see the REGISTERED TARGETS section for more
  632.           information).
  633.  
  634.           The "flags" are a bit mask of the following flags:
  635.           CUTPASTE_NORMAL_TYPE, CUTPASTE_FILENAME_TYPE, and
  636.           CUTPASTE_HIDDEN_TYPE.  Any new filename target as described here
  637.           needs to be flagged as a "CUTPASTE_FILENAME_TYPE" so that the
  638.           VkCutPaste class can deal with it properly.  A
  639.           "CUTPASTE_HIDDEN_TYPE" means that this target will never be
  640.           published to other clients.  This is unusual, but can be useful if
  641.           you are using an internal representation you do not wish to ever
  642.           expose.
  643.  
  644.           You can optionally specify a function that is called to destroy
  645.           auxiliary data associated with this data target.  An example usage
  646.           of the DestroyProc would be if you need to register a new target as
  647.           filename data (CUTPASTE_FILENAME_TYPE).
  648.  
  649.           cnp->registerDataType("MY_FILE", "MY_FILE", 8,
  650.               CUT_PASTE_FILENAME_TYPE, fileDestroyProc, NULL);
  651.  
  652.  
  653.      Before your client calls putCopy() with a filename target, it needs to
  654.  
  655.  
  656.  
  657.                                                                        PPPPaaaaggggeeee 11110000
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  665.  
  666.  
  667.  
  668.      create a file that will be given to the VkCutPaste class.  The VkCutPaste
  669.      class will call the DestroyProc when this file is no longer needed.
  670.  
  671.           cnp->putCopy(xaCLIPBOARD, "MY_FILE", filename, strlen(filename) + 1);
  672.  
  673.  
  674.      Now, when the VkCutPaste class no longer needs the file referenced by
  675.      filename, the DestroyProc is called.  For file targets, the DestroyProc
  676.      should remove the file.  In the DestroyProc, "data" is a copy of the data
  677.      that was made when your client called putCopy().  For this example, data
  678.      is the filename that was handed over to the VkCutPaste class.
  679.  
  680.           static void fileDestroyProc(Widget w, Atom selection, Atom target,
  681.             XtPointer data, unsigned long numBytes, void * clientData)
  682.           {
  683.               // DO NOT free the filename itself, just remove the file.
  684.               if (target == MY_FILE && data != NULL)
  685.               {
  686.                   char *fname = (char *)data;
  687.                   unlink(fname);
  688.               }
  689.           }
  690.  
  691.  
  692.      Notice that this is only necessary if you need to register a new data
  693.      type.  See the section "FILE AND DATA OWNERSHIP" for more information.
  694.  
  695.  
  696.    rrrreeeeggggiiiisssstttteeeerrrrDDDDrrrrooooppppSSSSiiiitttteeee(((())))
  697.            Boolean registerDropSite(Widget w,
  698.                        Atom *interestList, int interestListLen,
  699.                        DropSiteCallbackProc dropProc,
  700.                        void *clientData = NULL);
  701.  
  702.  
  703.           Registers a widget as a drop site.  The "interestList" is an ordered
  704.           list of what data targets the drop site will accept.  When another
  705.           client drops data on this widget, the "dropProc" will be called with
  706.           exactly one target.  That target is the earliest one found in the
  707.           interestList which the other client can supply, or that can be
  708.           converted to, see "registerConverter()").
  709.  
  710.    rrrreeeeggggiiiisssstttteeeerrrrDDDDrrrrooooppppSSSSiiiitttteeeeEEEExxxxtttteeeennnnddddeeeedddd(((())))
  711.            Boolean registerDropSiteExtended(Widget w,
  712.                        Atom *interestList, int interestListLen,
  713.                        DropSiteCallbackProc dropProc,
  714.                        DragCallbackProc dragProc = NULL,
  715.                        void *clientData = NULL,
  716.                        Arg *args = NULL, int numArgs = 0);
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.                                                                        PPPPaaaaggggeeee 11111111
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  731.  
  732.  
  733.  
  734.           This does exactly what "registerDropSite()" does, but provides more
  735.           options for the advanced programmer who needs more control.  For
  736.           example, the programmer could specify the various drop icons by
  737.           specifying those parameters in the "args" argument.  "Args" and
  738.           "numArgs" are passed off to XmDropSiteRegister().  The following
  739.           "args" are not allowed: XmNdragProc, XmNdropProc,
  740.           XmNdropSiteOperations, XmNinportTargets, XmNnumImportTargets. See
  741.           the XmDropSite man page for information on other valid arguments.
  742.           Motif's Drop Copy protocol (XmDROP_COPY) is the only drag and drop
  743.           operation supported.  Possible "reasons" that are passed to the
  744.           DragCallbackProc are:  XmCR_DROP_SITE_LEAVE_MESSAGE,
  745.           XmCR_DROP_SITE_ENTER_MESSAGE, and XmCR_DROP_SITE_MOTION_MESSAGE.
  746.  
  747.    rrrreeeeggggiiiisssstttteeeerrrrLLLLoooosssseeeeSSSSeeeelllleeeeccccttttiiiioooonnnn(((())))
  748.            Boolean registerLoseSelection(Atom selection,
  749.                        LoseSelectionProc loseSelProc,
  750.                        void *clientData);
  751.  
  752.  
  753.           The "loseSelProc" will be called when this application loses the
  754.           selection ownership to some other client.  This is very useful in
  755.           the case of PRIMARY, since in the loseSelProc callback the
  756.           application should un-highlight what was previously highlighted as
  757.           the PRIMARY selection.
  758.  
  759.    rrrreeeemmmmoooovvvveeee(((())))
  760.            Boolean remove(Atom selection, Atom target);
  761.  
  762.  
  763.           Removes the indicated "target" from the currently exported
  764.           selection.  For example, if you had called "putReference(XPM)" and
  765.           now the XPM data has become invalid for some reason, you must call
  766.           "remove(XPM)".
  767.  
  768.    sssseeeettttTTTTrrrraaaannnnssssaaaaccccttttiiiioooonnnnssssTTTTiiiimmmmeeeeoooouuuutttt(((())))
  769.            void setTransactionsTimeout(unsigned long numSeconds);
  770.  
  771.  
  772.           Sets the transaction timeout.  The default Motif timeout is 5
  773.           seconds, which means that if the remote client does not respond to a
  774.           request for data within 5 seconds, the transaction is canceled and
  775.           no data is transferred.  For some large data targets, or those that
  776.           require long conversions, 5 seconds may not be adequate.
  777.  
  778.    uuuunnnnrrrreeeeggggiiiisssstttteeeerrrrDDDDrrrrooooppppSSSSiiiitttteeee(((())))
  779.            Boolean unregisterDropSite(Widget w);
  780.  
  781.  
  782.           Unregisters a drop site.  This makes it stop accepting drops of any
  783.           kind.
  784.  
  785.  
  786.  
  787.  
  788.  
  789.                                                                        PPPPaaaaggggeeee 11112222
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  797.  
  798.  
  799.  
  800. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  801.      This section provides examples to help get you started using the
  802.      VkCutPaste class.  For a detailed description on data and file ownership
  803.      during cut/paste and drag/drop operations, see the section "FILE AND DATA
  804.      OWNERSHIP".
  805.  
  806.      There are four separate actions supported by the VkCutPaste class:
  807.  
  808.  
  809.            _C_O_P_Y
  810.           - make some data available to another X-Client
  811.            _P_A_S_T_E
  812.           - import data from another X-Client
  813.            _D_R_A_G
  814.           - drag some data away to another X-Client
  815.            _D_R_O_P
  816.           - accept some data that is dropped on us
  817.  
  818.  
  819.      Before you can use any of this support, you must instantiate the
  820.      VkCutPaste class in your program (probably at program startup).  This can
  821.      be done with the following two lines of code, where "someWidget" is any
  822.      widget in your Motif or ViewKit program that will be valid during the
  823.      lifetime of the VkCutPaste class:
  824.  
  825.  
  826.             #include <Vk/VkCutPaste.h>
  827.             cnp = new VkCutPaste(someWidget);
  828.  
  829.  
  830.  
  831.      _C_O_P_Y - In your application, let's imagine that an XPM image is currently
  832.      highlighted, and that the user has selected the Copy menu item from the
  833.      Edit menu.  In the menu Callback, you might put the following code:
  834.  
  835.  
  836.            extern XtPointer image;        // ptr to XPM Image buffer
  837.            extern unsigned long numBytes; // num bytes of Image data
  838.  
  839.            Atom xaCLIPBOARD = cnp->clipboardAtom();
  840.            Atom xaXPM = XmInternAtom(dpy, "XPM", False);
  841.  
  842.            cnp->clear(xaCLIPBOARD);       // clear clipboard
  843.            cnp->putCopy(xaCLIPBOARD, xaXPM, image, numBytes);
  844.            cnp->export(xaCLIPBOARD);      // make it available
  845.  
  846.  
  847.      Now any application on your desktop is able to "Paste" the data (assuming
  848.      of course that the destination application has implemented standard X-
  849.      Window Copy and Paste).  To make this data available on the PRIMARY
  850.      selection, you could simply substitute xaCLIPBOARD with XA_PRIMARY (or
  851.      cnp->primaryAtom()).
  852.  
  853.  
  854.  
  855.                                                                        PPPPaaaaggggeeee 11113333
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  863.  
  864.  
  865.  
  866.      _P_A_S_T_E - In your application, let's imagine that the user has selected the
  867.      Paste menu item from the Edit menu, and that you are willing to paste
  868.      either a GIF Image or an XPM Image. In the menu Callback, you might put
  869.      the following code:
  870.  
  871.  
  872.            XtPointer image;
  873.            unsigned long numBytes;
  874.            Atom targetRet;
  875.  
  876.            Atom xaCLIPBOARD = cnp->clipboardAtom();
  877.            Atom xaGIF = XmInternAtom(dpy, "GIF_89", False);
  878.            Atom xaXPM = XmInternAtom(dpy, "XPM", False);
  879.  
  880.            Atom interestList[2];
  881.            interestList[0] = xaGIF_89;  // we first prefer GIF Image
  882.            interestList[1] = xaXPM;     // we also accept XPM Image
  883.            int numItemsInList = 2;
  884.  
  885.            image = cnp->importImmediate(xaCLIPBOARD, interestList,
  886.                              numItemsInList, &targetRet, &numBytes);
  887.            if (image == NULL)
  888.                printf("No Images available.");
  889.            else if (targetRet == xaGIF)
  890.                printf("We received a GIF Image.");
  891.            else if (targetRet == xaXPM)
  892.                printf("We received an XPM Image.");
  893.  
  894.  
  895.      The image that is returned should eventually be freed with
  896.      "XtFree(image);" The list of "targets" you are willing to accept can be
  897.      arbitrarily long, and just happens to be "2" in this example.
  898.  
  899.  
  900.      _D_R_A_G - In your application, let's imagine that the user has just pressed
  901.      a mouse button down on an XPM Image and has begun dragging it out of your
  902.      application to be dropped on another application. At the moment you want
  903.      the drag to begin, you might put the following code:
  904.  
  905.  
  906.            extern XtPointer image;        // ptr to XPM Image data
  907.            extern unsigned long numBytes; // num bytes of Image data
  908.            extern XEvent *xev;            // X-event causing drag
  909.            extern Widget theWidget;       // widget where drag begins
  910.  
  911.            Atom xaXPM = XmInternAtom(dpy, "XPM", False);
  912.  
  913.            cnp->dragAwayCopy(theWidget, xev, xaXPM, image, numBytes);
  914.  
  915.  
  916.      The "dragAwayCopy" makes a copy of your data, and so you can free the
  917.      image data immediately after the call. There are two optional parameters
  918.  
  919.  
  920.  
  921.                                                                        PPPPaaaaggggeeee 11114444
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  929.  
  930.  
  931.  
  932.      that are not usually specified, but if you wish to know when the dragAway
  933.      is finished, or if the dragAway was successful or not, you can pass in a
  934.      callback procedure and any data you like. This would look like:
  935.  
  936.  
  937.            // dragAwayCB is invoked after completion of the dragAway
  938.            //
  939.            void dragAwayCB(Widget w, Boolean dragSuccess,
  940.                            XtPointer clientData)
  941.            {
  942.                printf("Drag success=%d.", dragSuccess);
  943.                printf("ClientData=%d.", clientData);
  944.            }
  945.  
  946.            cnp->dragAwayCopy(theWidget, xev, xaXPM, image, numBytes,
  947.                              dragAwayCB, (XtPointer) 123);
  948.  
  949.  
  950.  
  951.      _D_R_O_P - In your application, let's imagine that you want to accept a
  952.      "drop" on a certain widget of either an XPM Image or a GIF Image. After
  953.      you create the widget that will be "dropped" on, you might write the
  954.      following code:
  955.  
  956.  
  957.            Atom xaXPM = XmInternAtom(dpy, "XPM", False);
  958.            Atom xaGIF = XmInternAtom(dpy, "GIF_89", False);
  959.  
  960.            // dropProcCB - invoked whenever anyone drops an image
  961.            //              on the widget
  962.            //
  963.            void dropProcCB(Widget w, Atom target, XtPointer data,
  964.                            unsigned long numBytes, int x, int y,
  965.                            XtPointer clientData)
  966.            {
  967.              if (target == xaXPM)
  968.                  printf("XPM Image dropped at x=%d, y=%d.", x, y);
  969.              else if (target == xaGIF)
  970.                  printf("GIF Image dropped at x=%d, y=%d.", x, y);
  971.  
  972.              // eventually you should "XtFree(data)" to free the mem
  973.            }
  974.  
  975.            // this code is done once, and makes the indicated widget
  976.            // a "DropSite"
  977.            //
  978.            extern Widget theWidget;        // the widget that is
  979.                                            // to become a dropSite
  980.            Atom interestList[2];
  981.            interestList[0] = xaXPM;        // we first prefer XPM
  982.            interestList[1] = xaGIF_89;     // we also accept GIF
  983.            int numItemsInList = 2;
  984.  
  985.  
  986.  
  987.                                                                        PPPPaaaaggggeeee 11115555
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  995.  
  996.  
  997.  
  998.  
  999.            cnp->registerDropSite(theWidget, interestList,
  1000.                      numItemsInList, dropProcCB, (XtPointer) 123);
  1001.  
  1002.  
  1003.      The list of "targets" you accept on the DropSite can be arbitrarily long,
  1004.      and just happens to be "2" in this example.
  1005.  
  1006.  
  1007.  
  1008. AAAADDDDVVVVAAAANNNNCCCCEEEEDDDD EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  1009.      The above examples show the most simple uses of the VkCutPaste library.
  1010.      However, we support much more functionality for those programmers who
  1011.      wish to customize the behavior in some way, or have additional needs.
  1012.  
  1013.  
  1014.      _R_E_G_I_S_T_E_R_I_N_G _C_O_N_V_E_R_T_E_R_S - The VkCutPaste library provides integral support
  1015.      for converters. It has unified the interface, so that once the programmer
  1016.      registers one converter, it will convert for Drag, Drop, Copy and Paste
  1017.      invisibly. The example code below places only an XPM Image on the
  1018.      clipboard, yet the VkCutPaste class offers up both the XPM Image and also
  1019.      a GIF Image, because the appropriate converter has been registered.
  1020.  
  1021.  
  1022.            Atom xaXPM = XmInternAtom(dpy, "XPM", False);
  1023.            Atom xaGIF = XmInternAtom(dpy, "GIF_89", False);
  1024.            Atom xaCLIPBOARD = cnp->clipboardAtom();
  1025.            extern XtPointer image;        // ptr to XPM Image buffer
  1026.            extern unsigned long numBytes; // num bytes of Image data
  1027.  
  1028.            Boolean convertXPMtoGIF(Widget w, Atom selection,
  1029.              void *clientData, Atom srcTarget, XtPointer src,
  1030.              unsigned long numSrcBytes, Atom dstTarget,
  1031.              XtPointer *dst, unsigned long *numDstBytes)
  1032.            {
  1033.               // code to convert from XPM Image to GIF omitted, but
  1034.               // this will malloc space for the dst image, and set
  1035.               // *numDstBytes to indicate the number of bytes
  1036.               // malloc'ed, and set *dst to point at the new image
  1037.            }
  1038.  
  1039.            cnp->registerConverter(xaXPM, xaGIF, convertXPMtoGIF);
  1040.  
  1041.            cnp->clear(xaCLIPBOARD);       // clear clipboard
  1042.            cnp->putCopy(xaCLIPBOARD, xaXPM, image, numBytes);
  1043.            cnp->export(xaCLIPBOARD);      // make it available
  1044.  
  1045.  
  1046.      At this point, if any other application asks us for a GIF Image, we will
  1047.      supply it by calling the convertXPMtoGIF() converter function on the fly.
  1048.  
  1049.      Also, if we ask specifically to import a GIF at this point with the
  1050.  
  1051.  
  1052.  
  1053.                                                                        PPPPaaaaggggeeee 11116666
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1061.  
  1062.  
  1063.  
  1064.      following code:
  1065.  
  1066.  
  1067.            image = cnp->importImmediate(xaCLIPBOARD, &xaGIF, 1,
  1068.                                         &targetRet, &numBytes);
  1069.  
  1070.  
  1071.      then we will successfully get a GIF Image even if the remote client is
  1072.      only offering a XPM Image. The converter will fire during the
  1073.      "importImmediate()" call to supply us with the correct data. This same
  1074.      converter will fire automatically now on DragAway calls and also on Drop
  1075.      calls.
  1076.  
  1077.  
  1078. FFFFIIIILLLLEEEE AAAANNNNDDDD DDDDAAAATTTTAAAA OOOOWWWWNNNNEEEERRRRSSSSHHHHIIIIPPPP
  1079.      The pseudocode below details the ownership of files and data during
  1080.      different stages of cut/paste and drag/drop.  The examples show
  1081.      copy/paste and drag/drop of stream data, and of filename data.
  1082.  
  1083.      Filename data simply means the data that is transfered is a filename.
  1084.      For example, when transferring a XPM_FILE target, the data transferred is
  1085.      actually the filename, not the data contained in the file.  The receiving
  1086.      application will need to retrieve the filename, then access the file.
  1087.  
  1088.      The VkCutPaste class will only recognize targets as being filename
  1089.      targets if they have been registered with the CUTPASTE_FILENAME_TYPE flag
  1090.      (see registerDataType()).  See the "REGISTERED TARGETS" section below for
  1091.      a list of targets which have been pre-registered.
  1092.  
  1093.  
  1094.    AAAA nnnnooootttteeee oooonnnn ffffiiiilllleeeennnnaaaammmmeeee ttttaaaarrrrggggeeeettttssss
  1095.      It should be noted that applications should rarely need to use filename
  1096.      targets for cut/paste and drag/drop operations.  In fact exchanging
  1097.      filenames with other applications simply WILL NOT WORK when the sender
  1098.      and receiver applications are running on different computers.  When given
  1099.      a choice between filename targets and the corresponding data stream
  1100.      targets, applications should always exchange the data stream targets.
  1101.  
  1102.      In the examples below, cnp is an instance of the VkCutPaste class, and
  1103.      filename target is any target which has been registered with the
  1104.      CUTPASTE_FILENAME_TYPE flag (see registerDataType()).
  1105.  
  1106.      _C_o_p_y _o_f _F_i_l_e_n_a_m_e_s:
  1107.  
  1108.           //
  1109.           // Create a file on disk.  Ownership of the file will be transferred
  1110.           // to the VkCutPaste class at putCopy() time.
  1111.           //
  1112.           char *filename = create a file, return the malloc'ed filename;
  1113.  
  1114.           //
  1115.           // Clear any prior putCopy() or export().
  1116.  
  1117.  
  1118.  
  1119.                                                                        PPPPaaaaggggeeee 11117777
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1127.  
  1128.  
  1129.  
  1130.           //
  1131.           cnp->clear();
  1132.  
  1133.           //
  1134.           // Copies the filename 'filename', and transfers the ownership of the
  1135.           // file on disk to the VkCutPaste class.  Note that the file itself
  1136.           // is NOT copied, only the filename.  The client can now free the
  1137.           // memory used by filename, but must NOT reference the disk file
  1138.           // again.
  1139.           //
  1140.           cnp->putCopy(filename);
  1141.  
  1142.           //
  1143.           // The VkCutPaste class has made a copy of the filename, so the
  1144.           // original data should be freed by the client.
  1145.           //
  1146.           free(filename);
  1147.  
  1148.           //
  1149.           // Make the data available to other clients.
  1150.           //
  1151.           cnp->export();
  1152.  
  1153.  
  1154.            ...
  1155.  
  1156.           //
  1157.           // Some time later, if the VkCutPaste class gets a request for this
  1158.           // filename, the VkCutPaste class will clone the file, and hand off to          // the requesting client the cloned filename.  Ownership of this
  1159.           // cloned file is transferred to the requesting client.
  1160.           //
  1161.  
  1162.            ...
  1163.  
  1164.           //
  1165.           // The next time clear() is called, any data that has been copied
  1166.           // during prior putCopy() calls is freed, and any files that the
  1167.           // VkCutPaste class has obtained ownership of during prior putCopy()
  1168.           // calls are removed.  After this clear(), this VkCutPaste instance
  1169.           // no longer has any data available for export.
  1170.           //
  1171.           cnp->clear();
  1172.  
  1173.  
  1174.      _C_o_p_y _o_f _S_t_r_e_a_m _D_a_t_a:
  1175.  
  1176.           //
  1177.           // Create some data in memory.
  1178.           //
  1179.           char *data = create some data;
  1180.  
  1181.           //
  1182.  
  1183.  
  1184.  
  1185.                                                                        PPPPaaaaggggeeee 11118888
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1193.  
  1194.  
  1195.  
  1196.           // Clear any prior putCopy() or export().
  1197.           //
  1198.           cnp->clear();
  1199.  
  1200.           //
  1201.           // The VkCutPaste class makes a copy of the data.  This copy of
  1202.           // the data will be freed during the next "clear()" operation.
  1203.           //
  1204.           cnp->putCopy(data);
  1205.  
  1206.           //
  1207.           // The VkCutPaste class has made a copy of the data, so the original
  1208.           // data should be freed by the client.
  1209.           //
  1210.           free(data);
  1211.  
  1212.           //
  1213.           // Make the data available to other clients.
  1214.           //
  1215.           cnp->export();
  1216.  
  1217.            ...
  1218.  
  1219.           //
  1220.           // The next time clear() is called, any data that has been copied
  1221.           // during prior putCopy() calls is freed, and any files that the
  1222.           // VkCutPaste class has obtained ownership of during prior
  1223.           // putCopy() calls are removed.  After this clear(), this
  1224.           // VkCutPaste instance no longer has any data available for export.
  1225.           //
  1226.           cnp->clear();
  1227.  
  1228.  
  1229.      _P_a_s_t_e _o_f _F_i_l_e_n_a_m_e_s:
  1230.  
  1231.           //
  1232.           // Client requests a filename target.  The filename returned and
  1233.           // the corresponding file on disk are now owned by this client.  It
  1234.           // is therefore the responsibility of the requesting client to remove
  1235.           // (unlink()) the file when the client is finished with it, and
  1236.           // free the filename.
  1237.           //
  1238.           cnp->importImmediate(filename);
  1239.  
  1240.           //
  1241.           // After this client is done with the file, the file must be
  1242.           // removed, and the filename freed.
  1243.           //
  1244.           unlink(filename);
  1245.           free(filename);
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.                                                                        PPPPaaaaggggeeee 11119999
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1259.  
  1260.  
  1261.  
  1262.      _P_a_s_t_e _o_f _S_t_r_e_a_m _D_a_t_a:
  1263.  
  1264.           //
  1265.           // Client requests the data.  This data is now owned by this
  1266.           // client.  The client will use data, and should free it when
  1267.           // it is done processing the data.
  1268.           //
  1269.           cnp->importImmediate(data);
  1270.  
  1271.           //
  1272.           // Free the imported data when you are done processing it.
  1273.           //
  1274.           free(data);
  1275.  
  1276.  
  1277.      _D_r_a_g _o_f _F_i_l_e_n_a_m_e_s:
  1278.  
  1279.           //
  1280.           // Create a file on disk.  Ownership of the file will be
  1281.           // transferred to the VkCutPaste class at dragAwayCopy() time.
  1282.           //
  1283.           char *filename = create a file, return the malloc'ed filename;
  1284.  
  1285.           //
  1286.           // Copies the filename 'filename', and transfers the ownership of the
  1287.           // file on disk to the VkCutPaste class.  Note that the file itself
  1288.           // is NOT copied, only the filename.  The client can now free the
  1289.           // memory used by filename, but must NOT reference the disk file
  1290.           // again.  The VkCutPaste class will free this copy of the data, and
  1291.           // remove the file when the drag and drop operation is complete.
  1292.           //
  1293.           cnp->dragAwayCopy(filename);
  1294.  
  1295.           //
  1296.           // The VkCutPaste class has made a copy of the filename, so the
  1297.           // original data should be freed by the client.
  1298.           //
  1299.           free(filename);
  1300.  
  1301.            ...
  1302.  
  1303.           //
  1304.           // Some time later, if the VkCutPaste class gets a request for this
  1305.           // filename, the VkCutPaste class will clone the file, and hand off
  1306.           // the cloned filename to the requesting client.  Ownership of this
  1307.           // cloned file is transferred to the requesting client.   The
  1308.           // original file is removed when the drag and drop operation is
  1309.           // complete.
  1310.           //
  1311.  
  1312.  
  1313.      _D_r_a_g _o_f _S_t_r_e_a_m _D_a_t_a:
  1314.  
  1315.  
  1316.  
  1317.                                                                        PPPPaaaaggggeeee 22220000
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1325.  
  1326.  
  1327.  
  1328.           //
  1329.           // Create some data in memory.
  1330.           //
  1331.           char *data = create some data;
  1332.  
  1333.           //
  1334.           // The VkCutPaste class makes a copy of the data.  The VkCutPaste
  1335.           // class will free this copy of the data when the drag and drop
  1336.           // operation is complete.
  1337.           //
  1338.           cnp->dragAwayCopy(data);
  1339.  
  1340.           //
  1341.           // The client can now free the original data.
  1342.           //
  1343.           free(data);
  1344.  
  1345.  
  1346.      _D_r_o_p _o_f _F_i_l_e_n_a_m_e_s:
  1347.  
  1348.           //
  1349.           // The "drop" client registers a drop site.
  1350.           //
  1351.           cnp->registerDropSite(dropFilenameCallback);
  1352.  
  1353.            ...
  1354.  
  1355.           //
  1356.           // Some time later, the dropFilenameCallback() routine is called.
  1357.           // Inside of the dropFilenameCallback, the filename passed in and
  1358.           // the corresponding file on disk are now owned by this client.  It
  1359.           // is therefore the responsibility of the requesting client to remove
  1360.           // (unlink()) the file when the client is finished with it, and free
  1361.           // the filename.
  1362.           //
  1363.           dropFilenameCallback(filename)
  1364.           {
  1365.             // Do some processing on the file.
  1366.  
  1367.             unlink(filename);     // After this client is done with
  1368.                                   // the file, the file must be removed,
  1369.             free(filename);               // and the filename freed.
  1370.           }
  1371.  
  1372.  
  1373.      _D_r_o_p _o_f _S_t_r_e_a_m _D_a_t_a:
  1374.  
  1375.           //
  1376.           // The "drop" client registers a drop site.
  1377.           //
  1378.           cnp->registerDropSite(dropDataCallback);
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                                                                        PPPPaaaaggggeeee 22221111
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1391.  
  1392.  
  1393.  
  1394.            ...
  1395.  
  1396.           //
  1397.           // Some time later, the dropDataCallback() routine is called.
  1398.           //
  1399.           dropDataCallback(data)
  1400.           {
  1401.             // Do some processing with this data.
  1402.  
  1403.             //
  1404.             // Free the data when you are done processing it.
  1405.             //
  1406.             free(data);
  1407.           }
  1408.  
  1409.  
  1410.  
  1411. RRRREEEEGGGGIIIISSSSTTTTEEEERRRREEEEDDDD TTTTAAAARRRRGGGGEEEETTTTSSSS
  1412.    FFFFiiiilllleeeennnnaaaammmmeeee TTTTaaaarrrrggggeeeettttssss
  1413.      AIFF_C_FILE, AIFF_FILE, APPLE_QUICKTIME_FILE, AUTODESK_3DS_FILE,
  1414.      AUTODESK_DXF_FILE, AVID_OMFI_FILE, AVI_FILE, FITS_FILE, GIF_89_FILE,
  1415.      HTML_FILE, IGES_FILE, INVENTOR_2_0_FILE, INVENTOR_2_1_FILE, JFIF_FILE,
  1416.      MPEG_1_AUDIO_FILE, MPEG_1_VIDEO_FILE, NEXT_FILE, PGM_FILE, PHOTO_CD_FILE,
  1417.      PIXAR_RIB_FILE, PNM_FILE, PPM_FILE, SD2_FILE, SGI_AUDIO_FILE,
  1418.      _SGI_AUDIO_FILENAME, SGI_MOVIE_FILE, _SGI_MOVIE_FILENAME,
  1419.      SGI_RGBIMAGE_FILE, _SGI_RGB_IMAGE_FILENAME, SGI_SHOWCASE_FILE,
  1420.      SOFTIMAGE_DSC_FILE, SOFTIMAGE_HRC_FILE, TIFF_FILE, VRML_1_0_FILE,
  1421.      WAVERONT_OBJ_FILE, WAVE_FILE, XPM_FILE
  1422.  
  1423.  
  1424.    SSSSttttrrrreeeeaaaammmm TTTTaaaarrrrggggeeeettttssss
  1425.      AIFF, AIFF_C, APPLE_QUICKTIME, AUTODESK_3DS, AUTODESK_DXF, AVI,
  1426.      AVID_OMFI, BACKGROUND, BITMAP, CLASS, CLIENT_WINDOW, COLORMAP,
  1427.      COMPOUND_TEXT, DECNET_ADDRESS, DRAWABLE, FILE_NAME, FITS, FOREGROUND,
  1428.      GIF_89, HOSTNAME, HOST_NAME, HTML, IGES, INVENTOR, INVENTOR_2_0,
  1429.      INVENTOR_2_1, IP_ADDRESS, JFIF, MPEG_1_AUDIO, MPEG_1_SYSTEMS,
  1430.      MPEG_1_VIDEO, MULTIPLE, NAME, NEXT, ODIF, OWNER_OS, PGM, PHOTO_CD,
  1431.      PIXAR_RIB, PIXMAP, PNM, PPM, SD2, SGI_AUDIO, _SGI_AUDIO, _SGI_ICON,
  1432.      SGI_MOVIE, _SGI_MOVIE, SGI_RGBIMAGE, _SGI_RGB_IMAGE, SGI_SHOWCASE,
  1433.      SOFTIMAGE_DSC, SOFTIMAGE_HRC, STRING, TARGETS, TEXT, TIFF, TIMESTAMP,
  1434.      USER, VRML_1_0, WAVE, WAVERONT_OBJ, XPM
  1435.  
  1436.  
  1437. AAAAUUUUTTTTHHHHOOOORRRRSSSS
  1438.      VkCutPaste was written by Jim Young and Brian Wilson of Silicon Graphics,
  1439.      Inc.
  1440.  
  1441. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  1442.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt
  1443.           installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
  1444.           setDefaultResources(), getResources(), VkComponent(), manage(),
  1445.           unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w,
  1446.  
  1447.  
  1448.  
  1449.                                                                        PPPPaaaaggggeeee 22222222
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456. VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))                                                  VVVVkkkkCCCCuuuuttttPPPPaaaasssstttteeee((((3333xxxx))))
  1457.  
  1458.  
  1459.  
  1460.           deleteCallback
  1461.  
  1462.  
  1463. CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
  1464.      None
  1465.  
  1466. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  1467.      VkComponent, VkApp
  1468.      _I_n_t_e_r-_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n_s _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l, _V_e_r_s_i_o_n _2._0
  1469.      _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
  1470.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
  1471.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
  1472.      _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.                                                                        PPPPaaaaggggeeee 22223333
  1516.  
  1517.  
  1518.  
  1519.